Appendix A: 

This appendix contains the complete source code to two algorithm 
modules that exemplify an embodiment of the current invention: a finite 
impulse response filter module (FIR) and a filter group module (FIG). 
Although a digital filter is much too simple an algorithm to encapsulate as a 
component, it illustrates (and hopefully motivates) the concepts presented in 
the specification. The FIR filter example consists of the following files: 

1) fir.c, fir.h - FIR utility API module source and interface header 

2) ifir.c, ifir.h - abstract FIR interface definition header and 
parameter defaults 

3) fir_ti.c, fir_ti.h - vendor specific implementation and header 

4) fir_ti_ext.c - vendor specific extensions to FIR 

5) firtest.c, firtestl.c - simple programs using ALG to execute a FIR 
filter. 

The filter group module, FIG, is an example that illustrates how 
multiple instances of an algorithm can be grouped together to share common 
coefficients. 

The filter group example consists of the following files. 

1) fig.c, fig.h - FIG utility API module source and interface header 

2) ifig.h - abstract FIG interface definition header 

3) fig_ti.c, fig_ti.h - vendor specific implementation and header 

4) figtest.c - a simple program using ALG to execute a filter group. 

Table A-l summarizes a characterization of the performance of the FIR 
example, including memory usage requirements. A similar characterization 
can be compiled for the FIG example. 
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fir.h - FIR Module Interface 



Name 



fir.h - FIR Module Interface 



Text 



======== fir.h ======== 

This header defines all types, constants, 
applications that use the FIR algorithm. 



and functions used by- 



Applications that use this interface enjoy type safety and 
the ability to incorporate multiple implementations of the FIR 
algorithm in a single application at the expense of some 
additional indirection. 



#ifndef FIR_ 
#define FIR 



^include <alg.h> 
^include <ifir.h> 
#include <ialg.h> 



* = === = = = = FIR_Handle ======== 

* FIR algorithm instance handle 
*/ 

typedef struct IFIR_Obj *FIR_Handle; 



* ======== FIR_Params ======== 

* FIR algorithm instance creation parameters 
*/ 

typedef struct IFIR_Params FIR_Params; 



/* 

* ======== FIR_PARAMS = = = = = = = 

* Default instance parameters 
*/ 

#define FIR_PARAMS IFIR_PARAMS 



/* 

* ======== FIR_apply ======== 

* Apply a FIR filter to the input array and place results in the 

* output array. 
*/ 

extern Void FIR_apply (FIR__Handle fir, Int in[], Int out[3); 
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fir.h - FIR Module Interface 



/* ■ 

* ======== FIR_create ======== 

* Create an instance of a FIR object. 
*/ 

static inline FIR_Handle FIR_create ( const IFIR_Fxns *fxns, 

const FIR_Params *prms) 

{ 

return ( (FIR_Handle) ALG_create ( ( IALG_Fxns *)fxns, 

NULL, (IALG_Params *)prms)); 

> 

/* 

* ======== FIR_delete ======== 

* Delete a FIR instance object 

"■"Z static inline Void FIR_delete (FIR_Handle handle) 

^0 { 

ffl ALG_delete ( (ALG_Handle) handle) ; 

fn } 

ztr " 

fft /* 

III * == = === = = FIR_exit = = = ==== = 

* Module finalization 

-,D */ 

s extern Void FIR_exit (Void) ; 

G /* 

u] * ======== FIR_init ======== 

?e; * Module initialization 
**% */ 

*f extern Void FIR_init (Void) ; 

f~jj 

fl #endif /* FIR */ 
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ifir.h - Example Abstract FIR Filter Interface 



Name 



ifir.h - Example Abstract FIR Filter Interface 



Text 



/* 

* ======== ifir.h ======== 

* This header defines all types, constants, and functions shared by all 

* implementations of the FIR algorithm. 
*/ 

#ifndef IFIR_ 
#define IFIR 



#include <ialg.h> 
/* 

* ======== IFIR_Obj ======== 

* Every implementation of IFIR *must* declare this structure as 

* the first member of the implementation's object. 
*/ 

typedef struct IFIR_Obj { 

struct IFIR_Fxns *fxns; 
} IFIR_Obj ; 



====== IFIR_Handle ======== 

This type is a pointer to an implementation's instance object. 



typedef struct IFIR_Obj *IFIR_Handle ; 



/* 
* 



======== IFIR_Params ======== 

This structure defines the parameters necessary to create an 
instance of a FIR object. 



* Every implementation of IFIR *must* declare this structure as 

* the first member of the implementation's parameter structure. 
*/ 

typedef struct IFIR_Params { 

Int size; /* sizeof the whole parameter struct */ 

Int *coeffPtr; /* pointer to coefficients */ 

Int filterLen; /* length of filter */ 

Int frameLen; . /* length of input (output) buffer */. 

} IFIR_Params; 



/* 

* ======== IFIR_PARAMS ======== 

* Default instance creation parameters (defined in ifir.c) 
*/ 

extern IFIR Params IFIR P ARAMS ; 
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ifir.h - Example Abstract FIR Filter Interface 



/* 

* ======== IFIR_Fxns ======== 

* All implementation's of FIR must declare and statically 

* initialize a constant variable of this type. 
* 

* By convention the name of the variable is FIR_<vendor>_IFIR, where 

* <vendor> is the vendor name. 
*/ 

typedef struct IFIR_Fxns { 
IALG_Fxns ialg; 

Void (*filter) (IFIR_Handle handle, Int in[], Int out [] ) ,- 

} IFIR_Fxns; 

#endif /* IFIR_ */ 



fir.c - Common FIR Module Implementation 



Name 



fir.c - Common FIR Module Implementation 



Text 

/* 



* FIR Filter Module - implements all functions and defines all constant 

* structures common to all FIR filter algorithm implementations. 
*/ 

#include <std.h> 
#include <alg.h> 

#include <fir.h> 



y ^ 



* ======== FIR_apply ======== 

* Apply a FIR filter to the input array and place results in the 

* output array. 
*/ 

Void FIR_apply (FIR_Handle handle, Int in[], Int out [] ) 



{ 



/* activate instance object */ 
ALG activate ( (ALG Handle) handle) ; 



handle->f xns->f ilter (handle, in, out) 



/* filter data */ 



/* deactivate instance object */ 
ALG deactivate ( (ALG Handle) handle) ; 



Module finalization 



*/ 

Void FIR_exit() 
{ 



/* 

* ======== FIR_init ==== 

* Module initialization 
*/ 

Void FIR init() 
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fir_ti.c - Vender Specific FIR Module Implementation 



Name 



fir_ti.c - Vender Specific FIR Module Implementation 



Text 



/* 

* ========= f ir_ti_ialg. c ======== 

* FIR Filter Module - TI implementation of a FIR filter algorithm 
★ 

* This file contains an implementation of the IALG interface 

* required by XDAIS. 
*/ 

#pragma CODE_SECTION ( FIR_TI_activate , " . text : algActivate" ) 
#pragma CODE_SECTION ( FIR_TI_alloc , " . text : algAlloc ( ) " ) 
#pragma CODE_SECTION (FIR_TI_deactivate/ " . text : algDeactivate" ) 

C3 #pragma CODE_SECTION (FIR_TI_f ree , " . text : algFree" ) 

tfpragma CODE_SECTION { FIR_TI_initObj , " . text : alglnit " ) 

if* #pragma CODE_SECTION (FIR_TI_moved, " . text : algMoved" ) 

IT Hi 

'lU # include <std.h> 

ill 

CP #include <ialg.h> 

fy #include <ifir.h> 

#include <fir_ti.h> 

"""" #include <f ir_ti_priv.h> 

#include <string.h> /* memcpyO declaration */ 

#define HISTORY 1 
#define WORKBUF 2 
#define NUMBUFS 3 

/* 

* ======== dot ======== 

*/ 

static Int dot(Int *a, Int *b, Int n) 

{ 

Int sum = 0; 
Int i; 

for (i = 0; i < n; i++) { 
sum += *a++ * *b++; 

} 

return (sum) ; 

} 



fir_ti.c - Vender Specific FIR Module Implementation 



m 



ru 

H 

U5ST 

C3 



/* 

* ======== FIR_TI_activate ======== 

* Copy filter history from external slow memory into working buffer. 
*/ 

Void FIR_TI_activate (IALG_Handle handle) 
{ 

FIR_TI_Obj *fir = (Void *) handle; 



} 



/* copy saved history to working buffer */ 
memcpy { (Void * ) f ir->workBuf , (Void * ) f ir->history , 
f ir->f ilterLenMl * sizeof ( Int ) ) ; 
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fiMi.c - Vender Specific FIR Module Implementation 



5 : c 



/* 

* ======== FIR_TI_alloc ======== 

*/ 

Int FIR_TI_alloc (const IALG_Params *algParams, 

IALG_Fxns **pf, IALG_MemRec memTab [] ) 



{ 



const IFIR_Params *params = (Void * ) algParams ; 

if (params == NULL) { 

params = &IFIR_PARAMS ; /* set default parameters */ 

} 

/* Request memory for FIR object */ 
memTab [0] .size = sizeof (FIR_TI_0bj ) ; 
memTab [0] . alignment = 0; 
memTab [0] . space = IALG_EXTERNAL ; 
memTab [0] .attrs = IALG PERSIST; 



CO /* 

fft * Request memory filter's "inter-frame" state (i.e., the 

#U * delay history) 

=31 5 

= jf * Note we could have simply added the delay buffer size to the 

%Q * end of the FIR object by combining this request with the one 

s * above, thereby saving some code. We separate it here for 

f=3 * clarity. 

*/ 

memTab [HISTORY] . size = (params->f ilterLen - 1) * sizeof(Int); 
memTab [HISTORY] .alignment = 0 ; 
memTab [HISTORY] . space = IALG_EXTERNAL ; 
memTab [HISTORY] .attrs = IALGJPERSIST; 

/* 

* Request memory for shared working buffer 
*/ 

memTab [WORKBUF] . size = 

(params->f ilterLen - 1 + params->f rameLen) * sizeof(Int); 
memTab [WORKBUF] .alignment = 0; 
memTab [WORKBUF] . space = IALG_DARAM0 ; 
memTab [WORKBUF] . attrs = IALG SCRATCH; 



return (NUMBUFS) ; 

} 



firJLc - Vender Specific FIR Module Implementation 



/* 

* ======== FIR_TI_deactivate ======== 

* Copy filter history from working buffer to external memory 
*/ 

Void FIR_TI_deactivate(IALG_Handle handle) 

{ 

FIR_TI_Obj *fir = (Void *) handle; 



/* copy history to external history buffer */ 
memcpy ( (Void * ) f ir->history , (Void * ) f ir->workBuf , 
f ir->'f ilterLenMl * sizeof ( Int )) ; 



* ======== FIR_TI_f ilter ======== 

%J * / 

Void FIR_TI_f ilter (IFIR_Handle handle, Int in[], Int out [] ) 

m { 

fji FIR_TI_Obj *fir = (Void *) handle; 

ff\ Int *src = f ir->workBuf ; 

Int *dst = out; 
Int i; 

/* copy input buffer into working buffer */ 

memcpy ( (Void *) ( f ir->workBuf + fir->f ilterLenMl ) , (Void *) in, 
fir->f rameLen * sizeof (Int) ) ; 

/* filter data */ 

for (i = 0; i < fir->f rameLen; i++) { 

*dst++ = dot(src++, fir->coeff, fir->f ilterLenMl + 1); 

} 



/* shift filter history to start of work buffer for next frame */ 
memcpy((Void * ) f ir->workBuf , (Void *) ( f ir->workBuf + fir->f rameLen) , 
f ir->f ilterLenMl * sizeof (Int) ) ; 
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fir_ti.c- Vender Specific FIR Module Implementation 



* ======== FIR_TI_free ======== 

*/ 

Int FIR_TI_free (IALG_Handle handle, IALG_MemRec memTab [] } 
{ 

FIR_TI_Obj *fir = (Void *) handle; 
FIR_TI_alloc (NULL, NULL , memTab); 
memTab [HISTORY] .base = f ir->history ; 

memTab [HISTORY] . size = f ir->f ilterLenMl * sizeof ( Int) ; 

memTab [WORKBUF] .size = 

(fir->f ilterLenMl + f ir->f rameLen) * sizeof(Int); 
memTab [WORKBUF] .base = f ir->workBuf ; 



Cn } 



return (NUMBUFS) ; 



FIR_TI_initObj 



EM */ 

fU Int FIR_TI_initObj (IALG_Handle handle, 



{ 



const IALG_MemRec memTab [], IALG_Handle p, 
const IALG__Params *algParams) 



FIR_TI_Obj *fir = (Void *) handle; 
%Q const IFIR_Params *params = (Void *)algParams; 

fit 

f*% if (params == NULL) { 

~J params = &IFIR_PARAMS ; /* set default parameters */ 

} 



fir->coeff = params->coef f Ptr ; 
fir->workBuf = memTab [WORKBUF] . base ,* 
fir->history = memTab [HISTORY] . base ; 
fir->f ilterLenMl = params->f ilterLen - 1; 
fir->f rameLen = params- >f rameLen; 

return (IALG EOK) ; 



# • 



fir_ti.c - Vender Specific FIR Module Implementation 



/* 

* ======== FIR_TI_moved ======== 

*/ 

Void FIR_TI_moved(IALG_Handle handle, 

const IALG_MemRec memTab [], IALG_Handle p, 
const IALG Params *algParams) 

{ 

FIR_TI_Obj *fir = (Void *) handle; 

const IFIR__Params *params = (Void *)algParams,* 

if (params !- NULL) { 

fir->coeff = params->coef f Ptr ; 

} 

p fir->workBuf = memTab [WORKBUF] . base; 

,Fs fir->history = memTab [HISTORY] .base; 

« } 



In 

rU 



Example Algorithm Implementation jd'J~^> 



fir_ti.h - Vender Specific FIR Module Interface 



Name 



fir_ti.h - Vender Specific FIR Module Interface 



Text 



* ======== fir_ti.h ======== 

* Vendor specific (TI) interface header for FIR algorithm. 
* 

* Applications that use this interface enjoy type safety and 

* and minimal overhead at the expense of being tied to a 
O * particular FIR implementation. 



jpF= * This header only contains declarations that are specific 

* to this implementation. Thus, applications that do not 

* want to be tied to a particular implementation should never 



2 

Cm * include this header (i.e.; it should never directly 
Ell * reference anything defined in this header.) 

ru */ 

^ #ifndef FIR_TI_ 
% * #define FIR_TI_ 

O. #include <ialg.h> 

^include <irtc.h> 
fjj #include <itst.h> 

^include <ifir.h> 

C3 /* 

O * ======== FIR_TI_exit ======== 

* Required module finalization function 
*/ 

extern Void FIR_TI_exit (Void) ; 
- /* 

* ======== FIR_TI_init ======== 

* Required module initialization function 
*/ 

extern Void FIR_TI_init (Void) ; 
/* 

* ======== FIR_TI_IALG ======== 

* TI's implementation of FIR's IALG interface 
*/ 

extern IALG_Fxns F IR_T I_I ALG ; 
/* 

* ======== FIR_TI_IFIR ========, 

* TI's implementation of FIR's IFIR interface 
*/ 

extern IFIR Fxns FIR TI IFIR; 



firji.h - Vender Specific FIR Module Interface 



* ======== FIR_TI_IRTC ======== 

* TI's implementation of FIR' s IRTC interface 
*/ 

extern IRTC_Fxns FIR_TI_IRTC ; 
/* 

* ======== Vendor specific methods ======== 

* The remainder of this file illustrates how a vendor can 

* extend an interface with custom operations. 
★ 

* The operations below simply provide a type safe interface 

* for the creation, deletion, and application of TI's FIR filters. 

* However, other implementation specific operations can also 
f=l * be added. 

;s */ 

•is? 

m /* 

CM * ======== FIR_TI_Handle ======== 

m */ 

|p typedef struct FIR_TI_Obj *FIR_TI_Handle ; 



s * We don't add any new parameters to the standard ones defined 

O * by IFIR. 

5 */ 

iu typedef IFIR_Params FIR_TI_Params ; 

s =? 

O /* 

tj * ========= FIR_TI_PARAMS ======== 

pj * Define our defult parameters. 

*/ 

#define FIR_TI_PARAMS IFIR_PARAMS 
/* 



* Create a FIR_TI instance object. 
*/ 

extern FIR_TI_Handle FIR_TI_create (const FIR_TI_Params *params) ; 
/* 

* ======== FIR_TI_delete ======== 

* Delete a FIR_TI instance object. 
*/ 

extern Void FIR TI delete (FIR TI Handle handle); 
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fir_ ti. h - Vender Specific FIR Module Interface 



/* 

* ======== FIR_TI_nApply ======== 

* Apply specified FIR filter to n input frames and overwrite 

* input with the result. 
*/ 

extern Void FIR_TI_nApply (FIR_TI_Handle handle, Int inout [] , Int n) ; 
tfendif /* FIR_TI_ */ 



0 * 
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fir_ti_priv.h - Private Vender Specific FIR Header 



Name 



fir_ti_priv.h - Private Vender Specific FIR Header 



Text 



■c: - 

in 



* ======== f ir_ti_priv . h ======== 

* Internal vendor specific (TI) interface header for FIR 

* algorithm. Only the implementation source files include 

* this header; this header is not shipped as part of the 

* algorithm. 
* 

* This header contains declarations that are specific to 

* this implementation and which do not need to be exposed 

* in order for an application to use the FIR algorithm. 
*/ 

#ifndef FIR_TI_PRIV_ 
#define FIR_TI_PRIV_ 

#include <ialg.h> 
#include <irtc.h> 
#include <itst.h> 
#include <ifir.h> 
#include <log.h> 



typedef struct FIR_TI_Obj { 

IALG_Obj alg; /* 

IRTC_Mask mask; /* 

Int *workBuf; /* 

Int *coeff; /* 

Int *history; /* 

Int filterLenMl; /* 

Int frameLen; /* 

} FIR_TI_Obj ; 



MUST be first field of XDAIS algs * 
current test/diag mask setting */ 
on-chip scratch history */ 
on-chip persistant coeff */ 
off chip persistant history */ 
length of coefficient array - 1 */ 
length of input (output) buffer */ 



extern LOG_Obj *FIR_TI_rtcOut ; /* our output trace log */ 
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ffk 



/* 

* ======== FIR_TI_trace ======== 

* Our equivalent of " print f" 
*/ 

#define FIR_TI_trace ( f , al, a2) \ 
if (FIR_TI_rtcOut ! = NULL) { \ 
LOG_printf (FIR_TI_rtcOut, (f) , (al) , (a2) ) ; \ 

} 

extern Void FIR_TI_activate (IALG_Handle handle); 
extern Void FIR_TI_deactivate (IALG_Handle handle); 

extern Int FIR_TI_alloc { const IALG_Params *algParams, IALG_Fxns **pf, 

IALG_MemRec memTab[]); 

extern Int FIR TI free{IALG Handle handle, IALG MemRec memTabf]); 



extern Int FIR_TI_initObj (IALG_Handle handle, 
|R const IALG_MemRec memTab[], IALG_Handle parent, 

ff\ const IALG_Params *algParams) ,- 



extern Void FIR_TI_moved (IALG_Handle handle, 

const IALG_MemRec memTab[], IALG_Handle parent, 
s const IALG_Params *algParams) ; 

% g extern Void FIR__TI_f ilter { IFIR_Handle handle, Int in[], Int out [] ) ; 

a; = 

^ extern IRTC_Mask FIR_TI_rtcGet (IRTC_Handle handle); 
extern Void FIR_TI_rtcBind (LOG_Obj *log) ; 

extern Void FIR_TI_rtcSet ( IRTC_Handle handle, IRTC_Mask mask) ; 
#endif /* FIR TI PRIV */ 



firJLextc - Vender specific FIR Extensions 



rn 



ill 



Name 

Text 

7* 



fir_ti_ext.c - Vender specific FIR Extensions 



fir ti ext . c 



7 



#pragma CODE_SECTION ( FIR_TI_create, " . text : create" ) 
#pragma CODE_SECTION (FIR_TI_delete, " . text : delete" ) 
#pragma CODE_SECTION (FIR_TI_init , " . text : init" ) 
#pragma CODE_SECTION (FIR_TI_exit , " r text : exit" ) 

#include <std.h> 

#include <alg.h> 

#include <ialg.h> 

#include <fir.h> 

#include <ifir.h> 

#include <fir_ti.h> 
#include <f ir_ti_priv. h> 



* 

*/ 



FIR TI create 



FIR_TI_Handle FIR_TI_create (const FIR_Params *params) 



{ 



return ((Void * ) ALG_create ( &FIR_TI_IALG , NULL , ( IALG_Params *)params)) ; 



FIR TI delete 



Void FIR_TI_delete (FIR_TI_Handle handle) 
{ 



} 

/* 



ALG delete((ALG Handle) handle) ,- 



FIR TI exit 



Void FIR_TI_exit (Void) 
{ 

ALG exit () ; 



/* 

* ======== FIR_TI_init 

*/ 

Void FIR_TI_init(Void) 
{ 

ALG__init () ; 

} 
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fir_ti_ext.c - Vender specific FIR Extensions 



/* 

* ======== FIR_TI_nApply ======== 

*/ 

Void FIR_TI_nApply(FIR_TI_Handle handle, Int input [] , Int n) 
{ 

Int *in; 
Int i; 

ALG_activate ( (ALG_Handle) handle) ; 

for {in = input, i = 0; i < n; i++) { 

FIR_TI_f ilter { ( IFIR_Handle) handle , in, in) ; 
in += handle->f rameLen; 

} 

ALG_deactivate ( (ALG_Handle) handle) ; 
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fir_ti_irtc.c - Vendor Specific Implementation of IRTC Interface 



.CSS. 



Name 

Text 

/* 

* ======== f ir_ti_irtc . c ======== 

* Filter Module IRTC implementation - TI's implementation of the 

* IRTC interface for the FIR filter algorithm 
*/ 

#include <std.h> 

#include <irtc.h> 
#include <fir_ti.h> 
# include <f ir_ti _j?riv.h> 
#include <log.h> 

/* 

* ======== FIR_TI_rtcOut ======== 

* This module's output trace log. 
*/ 

LOGJDbj *FIR_TI_rtcOut = NULL; 
/* 

* ======== FIR_TI_rtcBind ======== 

*/ 

Void FIR_TI_rtcBind(LOG_Obj *log) 
{ 

FIR_TI_rtcOut = log; 

FIR_TI_trace { "FIR_TI_rtcBind ( Ox%lx) \n" , log, NULL) ; 

}. 
/* 

* ======== FIR_TI_rtcGet ======== 

*/ 

IRTC_Mask FIR_TI_rtcGet ( IRTC_Handle handle) 
{ 

FIR_TI_Obj *fir = (Void * ) handle ; 

FIR_TI_trace("FIR_TI_rtcGet(Ox%lx) = Ox%x\n // , handle, f ir->mask) ; 
return (f ir->mask) ; 

} 
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ftr_ti_irtc.c - Vendor Specific Implementation oflRTC Interface 



/* 

* ======== FIR_TI_rtcSet ======== 

*/ 

Void FIR_TI_rtcSet (IRTC_Handle handle, IRTC_Mask mask) 
{ 

FIR_TI_Obj *fir = {Void * ) handle; 

FIR_TI_trace{"FIR_TI__rtcSet (Ox%lx, Ox%x)\n", handle, mask) ; 
fir->mask = mask; 

} 




m 



ass. 



fir_ti_ifirvt.c - Vendor Specific IFIR Function Table 



Name 



fir_ti_ifirvt.c - Vendor Specific IFIR Function Table 



Text 



/* 



======== f ir_ti_if irvt . c ======== 

This file contains the function table definitions for all 
interfaces implemented by the FIR_TI module that derive 
from IALG 



V 5 



C3 
ru 



We place these tables in a separate file for two reasons: 

1. We want to allow one to one to replace these tables 
with different definitions. For example, one may 
want to build a system where the FIR is activated 
once and never deactivated, moved, or freed. 

2. Eventually there will be a separate "system build" 
tool that builds these tables automatically 

and if it" determines that only one implementation 
of an API exists, "short circuits" the vtable by 
linking calls directly to the algorithm's functions. 



*/ 

#include <std.h> 

#include <ialg.h> 
#include <ifir.h> 

#include <fir_ti.h> 
#include <f ir_ti_priv. h> 

#define IALGFXNS \ 



&FIR_TI_IALG, 


/* 


module ID */ 




\ 


FIR_TI_activate , 


/* 


activate */ 




\ 


FIR_TI_alloc, 


/* 


alloc */ 




\ 


NULL, 


/* 


control (NULL => no 


control ops) */ 


\ 


FIR_TI_deactivate , 


/* 


deactivate */ 




\ 


FIR_TI_f ree, 


/* 


free */ 




\ 


FIR_TI_initObj , 


/* 


init */ 




\ 


FIR TI moved, 


/* 


moved */ 




\ 


NULL 


/* 


numAllocO (NULL => 


IALG_MAXMEMRECS ) 


*/\ 



======== FIR_TI_IFIR ======== 

This structure defines TI's implementation of the IFIR interface 
for the FIR TI module. 



*/ 

IFIR_Fxns FIR_TI_IFIR = { 
IALGFXNS , 

FIR_TI_filter /* filter */ 

}; 



/* module_vendor_interf ace */ 
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fir_tijfirvt.c - Vendor Specific I FIR Function Table 



* ======== FIR_TI_IALG ======== 

* This structure defines TI's implementation of the IALG interface 

* for the FIR_TI module. 
*/ 

#ifdef _TI_ 

asm("_FIR_TI_IALG . set _FIR_TI_IFIR" ) ; 
#else 



/* 

* We duplicate the structure here to allow this code to be compiled and 
^ * run non-DSP platforms at the expense of unnecessary data space 
W * consumed by the definition below. 
t5 */ 

ffl IALG_Fxns FIR_TI_IALG = { /* module_vendor_interf ace */ 

ff% IALGFXNS 
- F " l. 

#endif 



fit 

O 




fir_tijrtcvtc - Vendor Specific IRTC Function Table 



Name 




Text 



/* 



* 



fir ti irtcvt.c 



* This file contains the function table definitions for the 

* IRTC interface implemented by the FIR_TI module. 



* We place these tables in a separate file for two reasons: 

* 1. We want allow one to one to replace these tables 

* with different definitions. For example, one may 

* want to build a system where the FIR is activated 

* once and never deactivated, moved, or freed. 



2. Eventually there will be a separate "system build" 
tool that builds these tables automatically 
and if it determines that only one implementation 
of an API exists, "short circuits" the vtable by 
linking calls directly to the algorithm's functions. 



*/ 

#include <std.h> 

# include <irtc . h> 

#include <fir_ti.h> 

#include <f ir_ti_priv. h> 



* This structure defines TI's implementation of the IRTC interface 

* for the FIR TI module . 



* 



* 



FIR TI IRTC 



*/ 

IRTC_Fxns FIR__TI_IRTC = { 

&FIR_TI_IALG, / 

FIR TI rtcBind, / 



/* module ID */ 



/* rtcBind */ 
/* rtcGet */ 
/* rtcSet */ 



FIR_TI_rtcGet , 
FIR TI rtcSet 



}; 
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firtestc- example client of FIR utility library 



Name 



firtestc - example client of FIR utility library 



m 



Text 

/* 

* ======== firtest.c ======== 

* This example shows how to use the type safe FIR "utility" 

* library directly by an application. 
*/ 

#include <std.h> 
#include <fir.h> 
#include <log.h> 

#include <fir ti.h> 



^B. #include <stdio.h> 



ff| extern LOG_Obj trace; 

rJ Int coeff[] = {l, 2, 3, 4, 4, 3, 2, l}; 
Int input [] = 1, 0, 0, 0, 0, 0, o}; 

#define FRAMELEN (sizeof (input) / sizeof (Int)) 
tfdefine FILTERLEN (sizeof (coeff) / sizeof (Int)) 

^ Int output [FRAMELEN] ; 



static Void display (Int a [] , Int n) ; 
/* 



main 



'/ 



Int main (Int argc, String argv[]) 

{ 

FIR_Params firParams; 
FIR_Handle fir; 

FIR_init(); 

firParams = FIR_PARAMS; 
firParams. filterLen = FILTERLEN; 
firParams . f rameLen = FRAMELEN ; 
firParams . coeff Ptr = coeff; 

if ((fir = FIR_create ( &FIR_TI_IFIR, &f irParams) ) != NULL) { 

FIR_apply (f ir , input, output); /* filter some data */ 

display (output , FRAMELEN) ; /* display the result */ 

FIR_delete (f ir) ; /* delete the filter */ 

Y 

FIR exit () ; 



return (0) ; 



firtestc - example client of FIR utility library 



Q 

m 



rU 



/* 

* ======== display ======== 

*/ 

static Void display(Int a[], Int n) 
{ 

Int i; 

for (i = 0; i < n; i++) { 

LOG_printf (Sttrace, "%d ", a[i]); 

} 

LOG__pr int f {&t race, " \n" ) ; 



Example Algorithm Implementation d"2y 



firtestl.c - example client ofALG, RTC, and FIR 



Name 



firtestl.c - example client of ALG, RTC, and FIR 



Text 



* 
* 

*/ 



======== firtestl.c ======== 

This example shows how the trace interface (if implemented) 
can be used by an application. It also shows how to create 
an algorithm instance object using the ALG interface. 

The ALG interface allows one to create code that can create 
an instance of *any* XDAIS algorithm at the cost of a loss of 
type safety. 



#include <std.h> 
#include <fir.h> 
#include <alg.h> 
#include <log.h> 
#include <ialg.h> 
#include <rtc.h> 



vy 

f J 



#include <fir_ti.h> 
extern LOG_0bj trace; 

Int coeff[] = {l f 2, 3, 4, 4, 3, 2, l} ; 
Int input [] = {l, 0, 0, 0, 0, 0, 0}; 

#define FRAMELEN (sizeof (input) / sizeof (Int)) 
#define FILTERLEN (sizeof (coeff) / sizeof (Int)) 

Int output [FRAMELEN] ; 

static Void display(Int a[], Int n) ; 



/* 

* ======== main ======== 

*/ 

Int main (Int argc, String argv [] ) 

{ 

FIR_Params firParams; 
ALG_Handle alg; 
RTC_Desc rtc; 

ALG_init () ; 
FIR_init () ; 
RTC_init () ,- 

/* bind output log to FIR_TI module */ 
RTC_bind ( &FIR_TI_IRTC , fctrace) ; 

/* create an instance of a FIR algorithm */ 
firParams = FIR P ARAMS ; 



A- 3 



firtestl.c - example client ofALG, RTC, and FIR 



f irParams . f ilterLen = FILTERLEN; 
f irParams . f rameLen = FRAMELEN; 
f irParams . coeffPtr = coeff; 

alg = ALG_create ( (IALG_Fxns * ) &FIR_TI_IFIR, NULL, 
(IALG_Params *) &f irParams) ; 

/* if the instance creation succeeded, create a trace descriptor */ 
if (alg ! = NULL RTC_create { &rtc, alg, &FIR_TI_IRTC) != NULL) { 

RTC_set <&rtc, RTC_ENTER) ; /* enable trace */ 

FIR_apply { (FIR_Handle) alg, input, output); /* filter data */ 
display (output , FRAMELEN) ; /* display result */ 



CP 

fn 

m 



} 



RTC_delete(&rtc) ; 
ALG_delete (alg) ; 



RTC_exit () 
FIR_exit () 
ALG_exit () 
return (0) 



/* delete rtc descriptor */ 
/* delete alg instance */ 



/* 

* ======== display ======== 

*/ 

static Void display (Int a [] , Int n) 
{ 

Int i ; 



for (i = 0; i < n; i++) { 

LOG_printf (&trace, "%d ", a[i]); 

} 

L0G_pr intf ( Sctrace , " \n" ) ; 
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fig.h - Filter Group Module Interface 



Name 



fig.h - Filter Group Module Interface 



Text 

/* 

* ======== fig.h ======== 

* Filter Group Module Header - This module implements a FIR 

* filter group object. A filter group object simply 

* maintains global state (common coefficients and working 

* buffer) multiple FIR objects. Thus, this module does not 

* have a "process" method, it only implements "activate" 

* "deactivate", and "getStatus" . 
*/ 

#ifndef FIG_ 
#define FIG 



&i 3 



Vts5 



#include <ifig.h> 

typedef struct IFIGJDbj *FIG_Handle; 
/* 



* Filter group instance creation parameters 
*/ 

typedef struct IFIG_Params FIG_Params; 

extern const FIG_Params FIG_PARAMS; /* default instance parameters */ 
/* 

* ======== FIG_Status ======== 

* Status structure for getting FIG instance attributes 
*/ 

typedef struct IFIG_Status FIG_Status; 



/* 



====== FIG_activate ======== 

extern Void FIG_activate (FIG Handle handle); 



* 

*/ 



FIG create 



extern FIG_Handle FIG_create (IFIG_Fxns *fxns, IFIG_Params *prms) ; 



/* 

* 



FIG deactivate 



'/ 



extern Void FIG_deacti vat e (FIG_Handle handle) ; 



/* 
* 



FIG delete 



extern Void FIG delete (FIG Handle f ir) ; 



fig.h - Filter Group Module Interface 



* ======== FIG_getStatus ======== 

*/ 

extern Void FIG_getStatus { FIG_Handle fig, FIG_Status *status) ; 
#endif /* FIG_ */ 



•Bf " 
ffjj 

~r - 
a: = 

sii 
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iftg.h - Example Abstract FIR Filter Group Interface 



Name 



ifig.h - Example Abstract FIR Filter Group Interface 



Text 



£fi 

sEp 

•sirs, 

fii 



/* 

* ======== ifig.h ======== 

* Filter Group Module Header - This module implements a FIR filter 

* group object. A filter group object simply maintains global state 

* (common coefficients and working buffer) multiple FIR objects. 

* Thus, this module does not have a "process" method, it only 

* implements "activate" and "deactivate" . 
*/ 

#ifndef IFIG_ 
#define IFIG_ 

#include <ialg.h> 



yj * Filter group instance creation parameters 
*/ 



typedef struct IFIG_Params { 

Int size; /* sizeof this structure */ 

Int *coeffPtr; /* pointer to coefficient array */ 

Int filterLen; /* length of coefficient array (words) */ 

} IFIG_Params; 



extern const IFIG_Params I F IG_PARAMS ; /* default instance parameters */ 



* ======== IFIG_Obj ====== 

*/ 

typedef struct IFIG_Obj { 

struct IFIG_Fxns *fxns,* 
} IFIG_Obj ; 



/* 

* ======== lFIG_Handle ======== 

*/ 

typedef struct IFIG_Obj *IFIG_Handle ; 



====== lFIG_Status ======== 

Status structure for getting FIG instance attributes 



*/ 

typedef struct IFIG_Status { 

Int *coeffPtr; /* pointer to coefficient array */ 

} IFIG_Status; 



iftg.h - Example Abstract FIR Filter Group Interface 



/* 

* ======== IFIG_Fxns ======== 

*/ 

typedef struct IFIG_Fxns { 
IALG_Fxns ialg; 

Void (*getStatus) (IFIG_Handle handle, IFIG_Status *status) ; 
} IFIG_Fxns; 

#endif /* IFIG_ */ 



3 
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fig.c - Common Filter Group Module Implementation 



Name 



fig.c - Common Filter Group Module Implementation 



Text 



/* 

* ======== fig.c ======== 

* Filter Group - this module implements a filter group; a group of FIR 

* filters that share a common set of coefficients and a working buffer. 
*/ 

#include <std.h> 
#include <fig.h> 



■5S=f 

m 

fn 
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FIG exit 



7 



Void FIG_exit (Void) 
{ 



*/ 



FIG init 



Void FIG_init (Void) 
{ 




fig_ti.c - Vendor-Specific Filter Group Implementation 



Name 



fig_ti.c -Vendor-Specific Filter Group Implementation 



Text 



* Filter Group - this module implements a filter group; a group of FIR 

* filters that share a common set of coefficients and a working buffer. 
*/ 

#pragma CODE_SECTION <FIG_TI_alloc, " . text : algAlloc ( ) " ) 
#pragma CODE_SECTION ( FIG_TI_f ree , " . text : algFree" ) 
tfpragma CODE_SECTION (FIG_TI_initObj , " . text : alglnit" ) 
#pragma CODE_SECTION (FIG_TI_moved, " . text : algMoved" ) 



#include <std.h> 

#include <ialg.h> 

#include <fig_ti.h> 

#include <ifig.h> 

#include <string.h> 



/* memcpy ( ) declaration */ 



#define COEFF 1 
tfdefine NUMBUFS 2 



typedef struct FIG_TI_Obj { 

IALG_Obj alg; 

Int *coeff; 

Int filterLen; 
} FIG_TI_Ob j ; 

/* 



FIG TI alloc 



/* MUST be first field of XDAIS algs */ 
/* on-chip persistant coefficient array */ 
/* filter length {in words) */ 



Int FIG_TI_alloc (const IALG_Params *algParams, IALG_Fxns * *parentFxns , 
IALG_MemRec memTab [] ) 

{ 

const IFIG_Params *params = (Void *)algParams; 

if (params == NULL) { 

params = &IFIG_PARAMS ; /* set default parameters */ 



/* Request memory for FIG object */ 
memTab [0] . size = sizeof (FIG_TI_0bj ) ; 
memTab [0] .alignment = 0; 
memTab [0] .space = IALG_EXTERNAL ; 
memTab [0] .at trs = I ALG PERSIST; 
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ftgji.c - Vendor-Specific Filter Group Implementation 



W 5 



} 



/* 

* Request memory for filter coefficients 

* Note that this buffer is declared as persistent; i.e., it is the 

* responsibility of the client to insure that its contents are 

* preserved whenever this object is active. 
*/ 

memTab [COEFF] . size = params->f ilterLen * sizeof (Int); 
memTab [COEFF] .alignment = 0; 
memTab [COEFF] . space = IALGJDARAM1 ; 
memTab [COEFF] .attrs = IALG_PERSIST ; 

return (NUMBUFS) ; 



/* 

CR * ======== FIG_TI_free ======== 

cn */ 

ff% Int FIG_TI_free (IALG_Handle handle, IALG_MemRec memTab [] ) 



{ 



FIG_TI_0bj *fig = (Void *) handle; 
FIG_TI_alloc(NULL, NULL, memTab); 
memTab [COEFF] .base = fig->coeff; 

memTab [COEFF] . size = fig->f ilterLen * sizeof (Int); 
return (NUMBUFS) ; 



======== FIG_TI_initObj ======== 



*/ 

Int FIG_TI_initObj (IALG_Handle handle, 

const IALG_MemRec memTab [] , IALG_Handle parent, 
const IALG Params *algParams) 

{ 

FIG_TI_0bj *fig = (Void *) handle; 

const IFIG_Params *params = (Void *)algParams; 

if (params == NULL) { 

params = &IFIG_PARAMS ; /* use defaults if algParams == NULL */ 

/* initialize the FIG object's fields */ 
fig->coeff = memTab [COEFF] .base; 
fig->f ilterLen = params->f ilterLen; 

/* copy coefficients into on-chip persistant memory */ 
memcpy ( (Void * ) f ig->coef f , 

(Void * ) params->coef f Ptr, params->f ilterLen * sizeof (Int)); 

return (IALG EOK) ; 
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/* 

* ======== FIG_TI_getStatus ======== 

*/ 

Void FIG_TI_getStatus (IFIG_Handle handle, IFIG_Status *status) 
{ 

FIG_TI_Obj *fig = (Void *) handle; 
status->coef f Ptr = fig->coeff ; 

} 

/* 

* ======== FIG_TI_moved ======== 

*/ 

Void FIG_TI_moved(IALG_Handle handle, 

const IALG_MemR.ec memTab [] , IALG_Handle parent, 
const IALG_Params *algParams) 



} 



FIG_TI_Obj *fig = (Void *) handle; 

/* initialize the FIG object's fields */ 
fig->coeff = memTab [COEFF] .base; 
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fig_ti.h - Vendor-Specific Filter Group Interface 



fig_ti.h - Vendor-Specific Filter Group Interface 
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m 



2 
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3 %r 



Name 

Text 

/* 

* ======== fig_ti.h ======= = 

* Vendor specific (TI) interface header for Filter Group algorithm 
*/ 

#ifndef FIG_TI_ 
#define FIG_TI_ 

#include <ialg.h> 
#include <ifig.h> 

/* 

* ======== FIG_TI_exit ======== 

* Required module finalization function 
*/ 

extern Void FIG_TI_exit (Void) ; 
/* 

* ======== FIG_TI_init ======== 

* Required module initialization function 
*/ 

extern Void FIG_TI_init (Void) ; 
/* 

* ======== FIG_TI_IALG ======== 

* TI's implementation of FIG'S IALG interface 
*/ 

extern IALG_Fxns F I G_T I_ I ALG ; 
/* 

* ======== FIG_TI_IFIG ======== 

* TI's implementation of FIG's IFIG interface 
*/ 

extern IFIG_Fxns FIG_TI_IFIG; 
#endif /* FIG TI */ 



4 - 3> & 




fig_tijfigvth - Vendor-Specific FIG Function Table 



Name 



fig_ti_ifigvt.h - Vendor-Specific FIG Function Table 



Text 



=bf - 



* ======== f ig_ti_if igvt . c ======== 

* This file contains the function table definitions for all interfaces 

* implemented by the FIG_TI module. 
*/ 

#include <std.h> 
#include <ialg.h> 
#include <ifig.h> 
#include <fig_ti.h> 
#include <f ig_ti jpriv. h> 



#define IALGFXNS \ 

&FIG_TI_IALG, /* 

NULL, /* 

FIG_TI_alloc, /* 

NULL, /* 

NULL, /* 

FIG_TI_free, /* 

FIG_TI_initObj , /* 

FIG_TI_moved, /* 

NULL /* 



implementation ID */ \ 

activate (NULL => nothing to do) */ \ 

alloc */ \ 
control (NULL => no control operations) */ \ 

deactivate {NULL => nothing to do) */ \ 

free */ \ 

init */ \ 

moved */ \ 
numAllocO (NULL => IALG_MAXMEMRECS) */ 



FIG TI IFIG 



IFIG_Fxns FIG_TI_IFIG 
IALGFXNS, 
FIG_TI_getStatus 



/* module_vendor_interf ace 
/* IALG functions */ 
/* IFIG getStatus */ 



======== FIG_TI_IALG ======== 

This structure defines TI ' s implementation of the IALG interface 
for the FIG TI module. 



*/ 
ttifdef 



TI 



asm("_FIG_TI_IALG .set _FIG_TI_IFIG" ) ; 
#else 
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fig^tijfigvt.h - Vendor-Specific FIG Function Table 



/* 

* We duplicate the structure here to allow this code to be compiled and 

* run non-DSP platforms at the expense of unnecessary data space 

* consumed by the definition below. 
*/ 

IALG_Fxns FIG_TI_IALG = { /* module_vendor_interf ace */ 

IALGFXNS, /* IALG functions */ 

}; 

#endif 



* 
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Name 

Text 

/* 



fig_ti_priv.h - Private Vendor-Specific Filter Group Header 



* 
★ 

*/ 



========= f ig_ti_priv.h ======== 

Internal vendor specific (TI) interface header for FIG 
algorithm. Only the implementation source files include 
this header; this header is not shipped as part of the 
algorithm. 

This header contains declarations that are specific to 
this implementation and which do not need to be exposed 
in order for an application to use the FIG algorithm. 



#ifndef FIG_TI_PRIV 
#define FIG_TI_PRIV 

#include <ialg.h> 

typedef struct FIG_TI_Obj { 

IALG_Obj alg; 

Int *coeff; 

Int filterLen; 
} FIG_TI_Obj ; 



/* MUST be first field of XDAIS algs */ 
/* on-chip persistant coeffient array */ 
/* filter length (in words) */ 



extern Int FIG_TI_alloc (const IALG_Params *,IALG_Fxns **, IALG_MemRec *) ; 
extern Int FIG_TI_f ree ( IALG_Handle, IALG_MemRec *) ; 

extern Void FIG_TI_ge t Status ( I FIG_Handle handle, IFIG_Status *status) ; 

extern Int FIG_TI_initObj ( IALG_Handle , 

const IALG_MemRec *, IALG_Handle, const IALG_Params *); 

extern Void FIGJTI_moved (IALG_Handle, 

const IALG_MemRec *, IALG_Handle, const IALG_Params *); 



#endif 
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figtest. c - Example Client of FIG and ALG 



Name 



figtest.c - Example Client of FIG and ALG 



Text 



/* 

* ======== figtest.c ======== 

* Example use of FIG, FIR and ALG modules. This test creates some 

* number of FIR filters that all share a common set of coefficients 

* and working buffer. It then applies the filter to the data and 

* displays the results. 
*/ 

#include <std.h> 
^include <fig.h> 

JSCS. - 1 

iJ ttinclude <fir.h> 
\Q #include <log.h> 
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#include <fig_ti.h> 
#include <fir_ti.h> 

extern LOG_Obj trace; 

#define NUM FRAMES 2 

#define NUMINST 4 
#define FRAMELEN 7 
#define FILTERLEN 8 

Int coeff [FILTERLEN] = { 

1, 2, 3, 4, 4, 3, 2, 1 

}; 

Int in [NUMINST] [FRAMELEN] = { 
{1, 0, 0, 0, 0, 0, 0}, 
{0, 1,. 0, 0, 0, 0, 0}, 
{0, 0, 1, 0, 0, 0, 0}, 
{0, 0, 0, 1, 0, 0, 0} 

}; 

Int out [NUMINST] [FRAMELEN] ; 



/* number of frames of data to process */ 

/* number of FIR filters to create */ 

/* length of in/out frames (words) */ 

/* length of coeff array (words) */ 

/* filter coefficients */ 



/* input data frames */ 



/* output data frames */ 



static Void display (Int a [] , Int n) ; 
/* 

* ======== main ======== 

*/ 

Int main {Int argc, String argv[]) 

{ 

FIG_Params figParams; 
FIR_Params firParams; 
FIG_Status f igStatus ; 
FIG_Handle group; 
FIR_Handle inst [NUMINST] ; 
Bool status; 



figtest.c - Example Client of FIG and ALG 



Int i, n; 

FIG_init {) ; 
FIR_init {) ; 

figParams = FIG_P ARAMS ; 
figParams. f ilterLen = FILTERLEN ; 
f igParams . coef f Ptr = coeff; 

/* create the filter group */ 

if ((group = FIG_create (&FIG_TI_IFIG, ScfigParams) ) != NULL) { 

/* get FIG pointers */ 
FIG_getStatus (group, fcfigStatus) ; 

C3 /* create multiple filter instance objects that reference group */ 

firParams = FIR_PARAMS; 
ff\ firParams . frameLen = FRAMELEN; 

^ firParams . f ilterLen = FILTERLEN; 

^ firParams . coef f Ptr ~ figStatus .coef f Ptr; 

for (status = TRUE, i = 0; i < NUMINST; i++) { 
CM inst[i] = FIR_create (&FIR_TI_IFIR, ScfirParams) ; 

fU if (inst[i] == NULL) { 

status = FALSE; 

} 

« } 

/* if object creation succeeded, apply filters to data */ 
%y if (status) { 

fjj /* activate group object */ 

f*% FIG_activate (group) ; 

'ZZ_ /* apply all filters on all frames */ 

l=s for (n = 0; n < NUMFRAMES ; n++) { 

for (i = 0; i < NUMINST; i++) { 

FIR_apply (inst [i] , in [i] , out [i] ) ; 
display (out [i] , FRAMELEN) ; 

} 

} 

/* deactivate group object */ 
FIG_deactivate (group). ; 

} 

/* delete filter instances */ 
for (i = 0; i < NUMINST; i++) { 
FIR_delete (inst [i] ) ; 

} 

/* delete filter group object */ 
FIG_delete (group) ; 

} 

FIG_exit () ; 
FIR exit () ; 
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return (0) ; 

} 

/* 

* ======== display ======== 

*/ 

static Void displaydnt a [] , Int n) 

{ 

Int i ; 

for {i = 0; i < n; i++) { 

LOG__printf (fctrace, " %d ", a[i]),- 

} 

LOGjprintf (fctrace, "\n") ; 



